<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">


<!-- remove old header -->


<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><title>cogen API Reference Documentation
        - Module: cogen</title><meta name="MSSmartTagsPreventParsing" content="true" /><meta http-equiv="imagetoolbar" content="no" /><link href="css/default.css" rel="stylesheet" type="text/css" /><link href="css/pygments.css" rel="stylesheet" type="text/css" />
    <!-- <link rel="shortcut icon" href="/images/favicon.ico" type="image/vnd.microsoft.icon"/> -->
    <link rel="stylesheet" href="css/apydia.css" type="text/css" />
    <script src="js/jquery-1.2.1.pack.js" type="text/javascript"></script>
    <script src="js/apydia.js" type="text/javascript"></script>
	<link rel="icon" href="images/favicon.ico" type="image/x-icon" />
</head>
<body>
    <div id="page">
        <div id="browser">
            <div class="browser-section">
                <h2>Module Index</h2>
                <ul>
                    <li class="active">
                        <a href="cogen.html">cogen</a>
                    </li><li>
                        <a href="cogen.common.html">cogen.common</a>
                    </li><li>
                        <a href="cogen.core.html">cogen.core</a>
                    </li><li>
                        <a href="cogen.core.coroutines.html">cogen.core.coroutines</a>
                    </li><li>
                        <a href="cogen.core.events.html">cogen.core.events</a>
                    </li><li>
                        <a href="cogen.core.pubsub.html">cogen.core.pubsub</a>
                    </li><li>
                        <a href="cogen.core.queue.html">cogen.core.queue</a>
                    </li><li>
                        <a href="cogen.core.reactors.html">cogen.core.reactors</a>
                    </li><li>
                        <a href="cogen.core.reactors.base.html">cogen.core.reactors.base</a>
                    </li><li>
                        <a href="cogen.core.reactors.iocp_proactor.html">cogen.core.reactors.iocp_proactor</a>
                    </li><li>
                        <a href="cogen.core.reactors.poll_reactor.html">cogen.core.reactors.poll_reactor</a>
                    </li><li>
                        <a href="cogen.core.reactors.qt_reactor.html">cogen.core.reactors.qt_reactor</a>
                    </li><li>
                        <a href="cogen.core.reactors.select_reactor.html">cogen.core.reactors.select_reactor</a>
                    </li><li>
                        <a href="cogen.core.schedulers.html">cogen.core.schedulers</a>
                    </li><li>
                        <a href="cogen.core.sockets.html">cogen.core.sockets</a>
                    </li><li>
                        <a href="cogen.core.util.html">cogen.core.util</a>
                    </li><li>
                        <a href="cogen.web.html">cogen.web</a>
                    </li><li>
                        <a href="cogen.web.async.html">cogen.web.async</a>
                    </li><li>
                        <a href="cogen.web.wsgi.html">cogen.web.wsgi</a>
                    </li>
                </ul>
            </div>
            <div class="browser-section">
                <h2>Submodules</h2>
                <ul>
                    <li>
                        <a href="cogen.common.html">common</a>
                    </li><li>
                        <a href="cogen.core.html">core</a>
                    </li><li>
                        <a href="cogen.web.html">web</a>
                    </li>
                </ul>
            </div>
        </div>
        <div id="content">
    <h1>Module:
        cogen
    </h1>
    <div class="docstring rst"><p>This is a library for network oriented, coroutine based programming.
The interfaces and events/operations aim to mimic some of the regular thread
and socket features.</p>
<p>cogen uses the <a class="reference" href="http://www.python.org/dev/peps/pep-0342/">enhanced generators</a>
in python 2.5. These generators are bidirectional: they allow to pass values in
and out of the generator. The whole framework is based on this.</p>
<p>The generator yields a <cite>Operation</cite> instance and will receive the result from
that yield when the operation is ready.</p>
<pre class="literal-block">
Roughly the cogen internals works like this:

+------------------------+
| @coroutine             |
| def foo():             |
|     ...                |             op.process(sched, coro)
|  +-&gt;result = yield op--|----------------+------------+
|  |  ...                |                |            |
+--|---------------------+    +---------------+  +---------------------+
   |                          | the operation |  | the operation can't |
  result = op.finalize()      | is ready      |  | complete right now  |
   |                          +------|--------+  +----------|----------+
  scheduler runs foo                 |                      |
   |                                 |                      |
  foo gets in the active             |                      |
  coroutines queue                   |                      |
   |                                 |                      |
   +----------------------&lt;----------+                      |
   |                                                    depening on the op
  op.run()                                               +---------+
   |      socket is ready               add it in        |         |
   +-------------&lt;------------  ......  the reactor   &lt;--+         |
   |                         later                                 |
   +------&lt;-------------------  ......  add it in some other     &lt;-+
    some event decides                  queue for later run
    this op is ready


The scheduler basicaly does 3 things:
 - runs active (coroutine,operations) pairs (calls process on the op)
 - runs the reactor
 - checks for timeouts

The reactor basicaly does 2 things:
 - calls the system to check what descriptors are ready
 - runs the operations that have ready descriptors

The operation does most of the work (via the process, finalize, cleanup,
run methods):
 - adds itself in the reactor (if it's a socket operation)
 - adds itself in some structure to be activated later by some other event
 - adds itself and the coro in the scheduler's active coroutines queue

The coroutine decorator wrappes foo in a Coroutine class that does some
niceties like exception handling, getting the result from finalize() etc.
</pre>
</div>
    <ul class="link-bar">
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/__init__.py#1">View source</a>
    </li>
</ul>
    <div>
        <h2>Modules</h2>
            <h3>
                <a href="cogen.common.html">common</a>
            </h3>
            <div class="docstring rst"><p>A module for quick importing the essential core stuff.
(coroutine, Scheduler, events, sockets, priority)</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.common.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/common.py#1">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.core.html">core</a>
            </h3>
            <div class="docstring rst"><p>This module holds the essential stuff.</p>
<p>Programming with this library should be straghtforward. A coroutine is just
a generator wrapped in a operation handling class:</p>
<div class="source"><pre><span class="nd">@coroutine</span>
<span class="k">def</span> <span class="nf">mycoro</span><span class="p">(</span><span class="n">bla</span><span class="p">):</span>
    <span class="k">yield</span> <span class="o">&lt;</span><span class="n">operation</span><span class="o">&gt;</span>
    <span class="k">yield</span> <span class="o">&lt;</span><span class="n">operation</span><span class="o">&gt;</span>
</pre></div>
<ul class="simple">
<li>the <cite>operation</cite> instructs the scheduler what to do with the
coroutine: suspend it till someting happens, add another coro in
the scheduler, raise a event and so on.</li>
<li>the <cite>operations</cite> are split up in 2 modules: events and sockets<ul>
<li>the <cite>operations</cite> from sockets are related to network, like reading and
writing, and these are done asynchronously but your code in the
coroutine will see them as a regular synchronous or blocking call.</li>
<li>the <cite>operations</cite> from events are related to signals and
coroutine/scheduler management.</li>
</ul>
</li>
<li>if a <cite>operation</cite> has a result associated then the yield will return that
result (eg. a string or a (connection, address) tuple) otherwise it will
return the operation instance.</li>
</ul>
<p>Typical example:</p>
<div class="source"><pre><span class="k">import</span> <span class="nn">sys</span><span class="o">,</span> <span class="nn">os</span>
<span class="k">from</span> <span class="nn">cogen.common</span> <span class="k">import</span> <span class="o">*</span>

<span class="nd">@coroutine</span>
<span class="k">def</span> <span class="nf">server</span><span class="p">():</span>
    <span class="n">srv</span> <span class="o">=</span> <span class="n">sockets</span><span class="o">.</span><span class="n">Socket</span><span class="p">()</span>
    <span class="n">srv</span><span class="o">.</span><span class="n">setblocking</span><span class="p">(</span><span class="mf">0</span><span class="p">)</span>
    <span class="n">srv</span><span class="o">.</span><span class="n">bind</span><span class="p">((</span><span class="s">'localhost'</span><span class="p">,</span><span class="mf">777</span><span class="p">))</span>
    <span class="n">srv</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="mf">10</span><span class="p">)</span>
    <span class="k">while</span> <span class="mf">1</span><span class="p">:</span>
        <span class="k">print</span> <span class="s">"Listening..."</span>
        <span class="n">conn</span><span class="p">,</span> <span class="n">addr</span> <span class="o">=</span> <span class="k">yield</span> <span class="n">sockets</span><span class="o">.</span><span class="n">Accept</span><span class="p">(</span><span class="n">srv</span><span class="p">)</span>
        <span class="k">print</span> <span class="s">"Connection from </span><span class="si">%s</span><span class="s">:</span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">addr</span>
        <span class="n">m</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">handler</span><span class="p">,</span> <span class="n">conn</span><span class="p">,</span> <span class="n">addr</span><span class="p">)</span>

<span class="nd">@coroutine</span>
<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">sock</span><span class="p">,</span> <span class="n">addr</span><span class="p">):</span>
    <span class="k">yield</span> <span class="n">sockets</span><span class="o">.</span><span class="n">Write</span><span class="p">(</span><span class="n">sock</span><span class="p">,</span> <span class="s">"WELCOME TO ECHO SERVER !</span><span class="se">\r\n</span><span class="s">"</span><span class="p">)</span>
    <span class="k">while</span> <span class="mf">1</span><span class="p">:</span>
        <span class="n">line</span> <span class="o">=</span> <span class="k">yield</span> <span class="n">sockets</span><span class="o">.</span><span class="n">ReadLine</span><span class="p">(</span><span class="n">sock</span><span class="p">,</span> <span class="mf">8192</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span> <span class="o">==</span> <span class="s">'exit'</span><span class="p">:</span>
            <span class="k">yield</span> <span class="n">sockets</span><span class="o">.</span><span class="n">Write</span><span class="p">(</span><span class="n">sock</span><span class="p">,</span> <span class="s">"GOOD BYE"</span><span class="p">)</span>
            <span class="n">sock</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
            <span class="k">return</span>

        <span class="k">yield</span> <span class="n">sockets</span><span class="o">.</span><span class="n">Write</span><span class="p">(</span><span class="n">sock</span><span class="p">,</span> <span class="n">line</span><span class="p">)</span>

<span class="n">m</span> <span class="o">=</span> <span class="n">Scheduler</span><span class="p">()</span>
<span class="n">m</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">server</span><span class="p">)</span>
<span class="n">m</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.core.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/core/__init__.py#1">View source</a>
    </li>
</ul>
            <h3>
                <a href="cogen.web.html">web</a>
            </h3>
            <div class="docstring rst"><p>This module holds a wsgi server and future web-related code.</p>
</div>
            <ul class="link-bar">
    <li>
        <a href="cogen.web.html">Details</a>
    </li>
    <li class="link-to-sourcecode">
        <a href="http://code.google.com/p/cogen/source/browse/trunk/cogen/web/__init__.py#1">View source</a>
    </li>
</ul>
    </div>
        </div>
        <div id="footer">
            Generated with <a href="http://apydia.ematia.de/" class="extern">
            Apydia 0.0.3</a>
        </div>
    </div>
</body>
</html>